Creating z/OS® component version using the v2 package format

Starting with HCL Launch version 7.0.5, you can create IBM® z/OS® component versions from a new package version called version 2 or v2. You can create v2 component versions using the buztool.sh command.

Currently, the artifacts are compressed at the partitioned data set (PDS) level and stored as binary files in Codestation, Nexus, or Artifactory. This condition makes HCL Launch z/OS® versions unique because distributed systems packages are stored at the artifact level and not at the folder level.

The cp command is enhanced in USS to provide a way to copy artifacts to and from MVS without losing meta relations like ALIAS. The HCL Launch v2 package format utilizes the enhanced cp command to package versions as-is and store them in Codestation, Nexus, or Artifactory.

You can benefit from several advantages by using the v2 package format:

  • Component version artifacts are downloaded from Codestation, Nexus, or Artifactory and viewed in an editor that supports viewing files in mainframe encoding. Artifacts are downloaded in native encoding that IBM® z/OS® uses rather than in ASCII.
  • During deployments, the token replacements are done in USS because these files are extracted in USS. This way, you deploy the token replaced artifacts directly into the target environment.
  • Merging component versions using the v2 package format has improved performances than merging in previous format
Note:
  • The current packaging format is still supported. The v2 package format is optional.
  • For better results, move components one at a time to the new package format. After an HCL Launch component starts using v2 package format, stay in that format for best results.
  • No change is required to the component process design to deploy component versions with the new package format.
  • No change is required to the rollback process.
  • Starting from version 7.1.0, you can merge component versions within the same package version. Note that merging is not supported between the v1 and v2 formats.

You can create component versions from the v2 package by using either of these methods:

  • In the buztool command, use the createzosversion2 option instead of createzosversion.
  • Use the -zpv v2 buztool parameter.
For example, use either of the following commands to create a new component version in the CICSModules component:
buztool.sh createzosversion2 -c CICSModules -v fixbug100 -s /u/ucduser/build/shiplist.xml
buztool.sh createzosversion -zpv v2 -c CICSModules -v fixbug100 -s /u/ucduser/build/shiplist.xml
Note:

The buztool properties file

Copying files from MVS to USS and back requires that you know the content type of the artifact. HCL Launch must determine whether the artifact is an executable file (like a loadlib file) or a binary file (like a DBRM file), or a text file (like a COBOL program). To do this, a property file must be passed as input to the buztool command with the -prop <property-file> parameter. This file contains the deployType to copyType mapping. Any number of unique deploy types can be mapped to any of the copy types: load, binary, or text. Deploy types must be prefixed with the deploytype parameter. Uncomment the parameters you want to use.

By default, container level deployType attributes in shiplist XML are mapped to below copy types :

LOAD -> Executable
OBJ (or) DBRM -> Binary
TEXT -> Text
Note: The values of EXTREPO.PASSWORD, EXTREPO.APIKEY, and SERVER.TOKEN are encrypted in the buztool.sh script. Change the properties file permission to write during the first run of buztool.sh script. You can set the file permission back to read-only later on for security reasons.
Below is an example of the buztool properties file:
# This property file contains samples for following
#
#   1) Defining Deploy Type and Copy Type mappings
#    (which will be later used to create version in new package format)
#
#   2) Setting Runtime Delta Deployment Flag
#
#   3) Defining External Repository details
#
#   4) Declaring alternate UCD Server details for creating version
#
# * All the lines in the properties file starting with "#" are comments
#   and can be kept as is for reference.
#
#   Please find detailed explaination for each section below
#
#
# Section - 1 :
# ~~~~~~~~~~~
#
# Defining Deploy Type and Copy Type mappings to create version in
# new package format.
#
# * Deploytypes are mandatory for every Dataset Container in shiplist
#   to create version in new package format.
# * Deploytypes must be prefixed with "deploytype."
#
# Example:
# -------
#
# If deployType is "CICSDBRM", a BINARY dataset then add entry as below
# deploytype.CICSDBRM=BINARY
#
# If deployType is "CICSLOAD", a EXECUTABLE then add entry as below
# deploytype.CICSLOAD=EXEC
#
# If deployType is "CICSLIB", a TEXT dataset then add entry as below
# deploytype.CICSLIB=TEXT
#
# * Property file will have below entries.
#
# deploytype.CICSDBRM=BINARY
# deploytype.CICSLOAD=EXEC
# deploytype.CICSLIB=TEXT
#
#  Add deploytypes to the list as needed.
#
# NOTE:
# ----
# * DeployType is unique in the property file
#   i.e., each deployType must be assigned to only one copyType.
#
deploytype.JCL=TEXT
# Above entry is used to define deploytype with JCL to copyType as TEXT
# to create a version in new package format from below script
# /var/ucd/agents/senthil/v7102/installTest/zossamples/test-create-version-new-format.sh
#
#
# Section - 2 :
# ~~~~~~~~~~~
#
# Setting Runtime Delta Deployment Flag.
#
# Example:
#
# Defining property as below skips the Runtime Delta Deployment
# calculations Logic.
# RUNTIME.DELTADEPLOY=FALSE
#
# NOTE:
# ----
# * Default it is considered as TRUE for version creation.
#
# Section - 3 :
# ~~~~~~~~~~~
# Defining details to store version artifacts to an external repository.
#
# Example:
#
# # Common external repository inputs
# EXTREPO.REPOSITORY_TYPE={Artifactory/Nexus}
# EXTREPO.USERNAME=
# EXTREPO.PASSWORD=
# EXTREPO.URL=
# EXTREPO.REPOSITORY=
#
# # Additional inputs, if external respository type is "Artifactory"
# EXTREPO.APIKEY=
# EXTREPO.httpProxyPort=
# EXTREPO.httpProxyHost=
#
# # Additional inputs, if external respository type is "Nexus"
# EXTREPO.RAWDIRECTORY=
#
#
# Section - 4 :
# ~~~~~~~~~~~
#
# Declaring alternate UCD Server details to create version
#
# Example:
#
# Buztool requires below two properties to create a version on a
# alternate UCD Server
#
# SERVER.URL=
# SERVER.TOKEN=
#
# NOTE:
# ----
# * On default, buztool creates version on a UCD Server defined during
#   installation
#